Before Clarity

I f you're at all like me, you've spent a lot of time thinking about what makes " good design " good. Most software developers become preoccupied with this question at some point in their careers, usually after witnessing the effects of bad design first hand. At that point, we start to reflect. We go through a stage where we feel we know what good design is but can't really define it. Then we learn various design principles and rules of thumb that make it easier to judge what constitutes good design. But when these principles and rules conflict, we have to make trade-offs and decide what's most important in each situation. To help me out, a few years ago I created my own blanket rule of thumb: Keep design as clear as possible. I was pretty sure that, regardless of the trade-offs, the most important thing was clarity. If a system uses a straightforward coding style—the classes and methods are well named and small enough to be clearly understood, and the system isn't littered with snarls of obscure code—then you can do just about anything. You can change the system with impunity, write tests for it, make adjustments , and add features, all with relative ease. So " clear design is good design " seemed like a reasonable rule of thumb because so much of what makes code impossible to maintain comes down to a lack of clarity. If you can understand your system, you can change it effectively. If you can't, it's much harder. Sounds simple and straightforward, right? Well, it might be a little too simple. Recently, I've discovered that I'm periodically sacrificing clarity and subordinating it to another standard. Let's take a look at an example. In Figure 1, we have some reasonably clear code for a method on a C++ class in a trading application. The adjustedShares method computes the number of shares that should be sold under certain circumstances. To do this, it gets information from a static method named getRateAdjustment on a class named TradeUtils. TradeUtils is just a utility class. All of its methods are static. So, what would we do if we needed to change the way getRateAdjustment calculates baseAdjustment? The answer seems relatively straightforward—we'd go into the code and change the calculation. But how would we know if we got it right? The most direct way to ensure that our …